# Node Polyfill 插件

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-node-polyfill" />

:::tip Node Polyfill 介绍
通常情况下，我们不会在浏览器端使用 Node 模块。但在当前代码需要同时在 Node 端和浏览器端运行时，用到一些 Node 模块是有可能的。Node Polyfill 为这些 Node 模块提供了浏览器版本的 polyfills。
:::

通过使用 Node Polyfill 插件，会自动注入 Node 核心模块在浏览器端的 polyfills，让你可以在浏览器端放心使用这些模块。

## 快速开始

### 安装插件

你可以通过如下的命令安装插件:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-node-polyfill -D" />

### 注册插件

你可以在 `rsbuild.config.ts` 文件中注册插件：

```ts title="rsbuild.config.ts"
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';

export default {
  plugins: [pluginNodePolyfill()],
};
```

## Node Polyfills

### Globals

- `Buffer`
- `process`

当你在代码中使用以上全局变量时，对应的 polyfill 会被自动注入。

比如以下代码会注入 `Buffer` 的 polyfill：

```ts
const bufferData = Buffer.from('some words');
```

你可以通过插件的 `globals` 选项来关闭该行为：

```ts
pluginNodePolyfill({
  globals: {
    Buffer: false,
    process: false,
  },
});
```

### Modules

- `assert`
- `buffer`
- `console`
- `constants`
- `crypto`
- `domain`
- `events`
- `http`
- `https`
- `os`
- `path`
- `punycode`
- `process`
- `querystring`
- `stream`
- `_stream_duplex`
- `_stream_passthrough`
- `_stream_readable`
- `_stream_transform`
- `_stream_writable`
- `string_decoder`
- `sys`
- `timers`
- `tty`
- `url`
- `util`
- `vm`
- `zlib`

当你通过 `require` 或 `import` 等语法在代码中引用以上模块时，对应 polyfill 会被注入。

```ts
import { Buffer } from 'buffer';

const bufferData = Buffer.from('abc');
```

### Fallbacks

- `child_process`
- `cluster`
- `dgram`
- `dns`
- `fs`
- `module`
- `net`
- `readline`
- `repl`
- `tls`

目前浏览器端没有以上模块的 polyfill，因此当你引用以上模块时，会自动 fallback 为一个空对象。

```ts
import fs from 'fs';

console.log(fs); // -> {}
```

## 选项

### globals

用于指定是否注入全局变量对应的 polyfill。

- **类型：**

```ts
type Globals = {
  process?: boolean;
  Buffer?: boolean;
};
```

- **默认值：**

```ts
const defaultGlobals = {
  Buffer: true,
  process: true,
};
```

### protocolImports

是否 polyfill 以 `node:` 开头的 Node.js 内置模块。

- **类型：** `boolean`
- **默认值：** `true`

比如关闭 `protocolImports`，将不会对 `node:path`，`node:http` 等模块进行 polyfill 注入。

```ts
pluginNodePolyfill({
  protocolImports: false,
});
```
